home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac 1 / Ian and Stuart's One (Australia).iso / Australasian Legends / Commercial / Rainbow Hill / MacDOS™ 2.0.0 / User's Guide / 07 Global Variables < prev    next >
Text File  |  1994-09-20  |  12KB  |  290 lines
  1. 7  Global Variables
  2.        Global  variables are just a way of saving character strings
  3.        for  later  use.  They are referred to as  "global"  because
  4.        they  are accessible from within all batch programs as  well
  5.        as interactively.
  6.  
  7.        MacDOS  automatically  generates  and  uses  some  variables
  8.        called "System Variables".
  9.  
  10. Creating and Setting Variables
  11.        You  can  set  global variables interactively  or  in  batch
  12.        programs  with the command SET. When you SET a variable  for
  13.        the  first time, MacDOS automatically creates it. The format
  14.        of SET is very simple:
  15.           set variable name=whatever string you like
  16.  
  17.        Any  string can be used to name such user-defined variables,
  18.        but be aware that:
  19.          •    If  you  include  a percent sign, this  will  confuse
  20.           MacDOS  when  you try to use the variable in  a  command,
  21.           because  percent signs are used to access  the  value  of
  22.           variables (see below).
  23.          •     If  you  include  double  quotes  or  other  special
  24.           characters  like  colons, slashes,  and  backslashes  you
  25.           might  run into problems later when you use the  variable
  26.           in  batch programs. At the very least, you will  find  it
  27.           confusing when reading your program.
  28.          •     When  recording  a  variable  name,  MacDOS  ignores
  29.           leading  and trailing spaces and tabs. That is, you  will
  30.           not  be  able to create a variable name which  begins  or
  31.           ends with blanks.
  32.          •    MacDOS  also simplifies all sequences of  spaces  and
  33.           tabs  found within variable names, so that words  forming
  34.           a variable name are always separated by single spaces.
  35.  
  36.        The  string which follows the equal sign is stored as it is,
  37.        including leading and trailing blanks.
  38.  
  39.        When  you  SET an existing variable, MacDOS simply  replaces
  40.        the current value with the new one.
  41.  
  42. Displaying and Removing Variables
  43.        To  display  a  list  of the existing  variables  and  their
  44.        content,  just  type  the  command SET  without  parameters.
  45.        MacDOS  then  displays all the variables  in  the  order  in
  46.        which they were created.
  47.  
  48.        You  can also display the string stored in a single variable
  49.        by typing:
  50.           ECHO %varName%
  51.  
  52.        When you do not need a user-defined variable anymore, it  is
  53.        a  good practice to remove it from the system. To do so, SET
  54.        the   variable   to  an  empty  string  by   typing   return
  55.        immediately  after  the  equal sign.  System  variables  are
  56.        special,  in  that they cannot be removed from  the  system.
  57.        When  you SET a system variable to the empty string,  MacDOS
  58.        does not remove it but sets it back to its default value.
  59.  
  60. Retrieving Variables
  61.        You  can access the string stored in a variable by inserting
  62.        in  a  command the variable name enclosed between a pair  of
  63.        percent  signs.  For  example, you can define  the  variable
  64.        HOME  by executing SET HOME=%WHERE% and then attach back  to
  65.        that  folder with CHDIR %HOME% . Similarly, if the  variable
  66.        RET_LBL  contains a label name, you can jump to  that  label
  67.        with the command GOTO %RET_LBL% .
  68.  
  69.        If   you   type   two  consecutive  percent  signs,   MacDOS
  70.        recognises  that  you are not attempting to  de-reference  a
  71.        variable or a replaceable parameter and handles the pair  of
  72.        characters as a single percent sign.
  73.  
  74. Operations on Variables
  75.        MacDOS   provides  a  series  of  commands  which  let   you
  76.        manipulate  global  variables. They are: INCR,  DECR,  SSTR,
  77.        and  TOUPPER.  If you need to keep the original  value,  use
  78.        SET to save it before executing any of these commands.
  79.  
  80.    INCR
  81.        INCR  has the purpose of incrementing numeric values, adding
  82.        numbers,   and   extending  or  concatenating   alphanumeric
  83.        strings.
  84.  
  85.        incr numVar
  86.        incr numVar by 7
  87.        incr numVar by -3
  88.        are  examples in which INCR is used to increment the numeric
  89.        value  stored  in the global variable numVar.  In  the  last
  90.        example,  the final value is actually less than the  initial
  91.        one, because the increment is negative.
  92.  
  93.        incr numVar by %anotherNumVar%
  94.        shows  how  INCR  can  be  used to  add   anotherNumVar   to
  95.        numVar.
  96.  
  97.        incr var by " append this"
  98.        incr -var by "prepend this "
  99.        incr var by anAlphaVar
  100.        incr alphaVar by 3
  101.        incr -alphaVar by 3
  102.        are  examples of how INCR can be used to attach  strings  to
  103.        each  other.  In  the last two examples,  three  spaces  are
  104.        appended and prepended to alphaVar respectively.
  105.  
  106.    DECR
  107.        DECR   has  the  purpose  of  decrementing  numeric  values,
  108.        subtracting   numbers,   and   truncating   or   subtracting
  109.        alphanumeric strings.
  110.  
  111.        decr numVar
  112.        decr numVar by 7
  113.        decr numVar by -3
  114.        are  examples in which DECR is used to decrement the numeric
  115.        value  stored  in the global variable numVar.  In  the  last
  116.        example,  the  final  value  is actually  greater  than  the
  117.        initial one, because the decrement is negative.
  118.  
  119.        decr numVar by %anotherNumVar%
  120.        shows how DECR can be used to subtract  anotherNumVar   from
  121.        numVar.
  122.  
  123.        decr var by " remove this from the end"
  124.        decr -var by "remove this from the beginning"
  125.        decr var by anAlphaVar
  126.        decr alphaVar by 3
  127.        decr -alphaVar by 3
  128.        are  examples  of  how DECR can be used to subtract  strings
  129.        from  each  other. In the last two examples, the three  last
  130.        and    first   characters   are   removed   from    alphaVar
  131.        respectively.
  132.  
  133.    SSTR
  134.        SSTR  extracts  a substring from a variable (the  name  SSTR
  135.        stands  for  SubSTRing). In order to  identify  what  should
  136.        remain  and  what should be removed, SSTR uses a  string  as
  137.        delimiter. Its format is:
  138.           sstr var delim
  139.        where   delim   is the string which SSTR uses to  split  the
  140.        variable.
  141.  
  142.        By  default,  SSTR  searches  for  the  delimiter  from  the
  143.        beginning   of   the  variable  string,  and  extracts   the
  144.        substring on the left of the delimiter. Optionally, you  can
  145.        direct  SSTR  to search from the end rather  than  from  the
  146.        beginning,  and to keep the substring on the  right  of  the
  147.        delimiter rather than on its left.
  148.  
  149.    TOUPPER
  150.        TOUPPER  converts the value of a variable to upper case.  It
  151.        is  useful  when you want to compare strings  and  filenames
  152.        ignoring upper and lower cases. Note that diacritical  marks
  153.        and  international characters are converted correctly: ü  to
  154.        Ü, æ to Æ, ø to Ø, etc.
  155.  
  156. System and Special Variables
  157.        Currently,   MacDOS   implements  seven  system   variables:
  158.        PROMPT,  DIRCMD, PATH, WHERE, CREATOR, QUOTE, and  FONTSIZE.
  159.        MacDOS  also uses the variables DOSERR, SHOWAE, and TIMEOUT,
  160.        which  behave like user-defined variables and can  therefore
  161.        be removed.
  162.  
  163.    PROMPT
  164.        stores  the  format  of the string displayed  by  MacDOS  to
  165.        prompt you for a new command.
  166.  
  167.        By  using  a dollar sign as an escape character, PROMPT  can
  168.        memorise  requests to display special information, like  the
  169.        current  date  and time, the specification  of  the  current
  170.        folder, the current volume ID, and the MacDOS version.
  171.  
  172.        Instead  of  setting the variable PROMPT  with  the  command
  173.        SET,  you  should use the command PROMPT. This would  ensure
  174.        that you set the prompt string to a valid value.
  175.  
  176.        By  default,  the  prompt  string consists  of  the  current
  177.        volume  ID  followed by a "greater than" sign (PROMPT=$n$g).
  178.        Please refer to the command reference section on PROMPT  for
  179.        a list of dollar-options.
  180.  
  181.    DIRCMD
  182.        stores the default options for the commands DIR and TREE.
  183.  
  184.        By  default, DIR and TREE list all visible files and folders
  185.        in  extended  format, non recursively, non sorted,  and  not
  186.        case  sensitive.  Please  refer  to  the  command  reference
  187.        section on DIR for a list of valid options.
  188.  
  189.    PATH
  190.        stores  the  list  of  folders  that  MacDOS  searches  when
  191.        looking  for  batch  programs,  applications,  AppleScripts,
  192.        MacDOS extensions, and abbreviation files.
  193.  
  194.        The folder specifications are separated by semicolons.
  195.  
  196.        When  you direct MacDOS to execute a program or look for  an
  197.        abbreviation file, MacDOS searches the current folder for  a
  198.        file  of  the appropriate type with the requested  name.  It
  199.        then  searches the folders specified in PATH,  scanning  the
  200.        list from left to right.
  201.  
  202.        MacDOS  initialises the system variable PATH  to  the  empty
  203.        string.  Therefore,  by  default MacDOS  only  searches  the
  204.        current folder.
  205.  
  206.        To  set the variable PATH you can also use the command  with
  207.        the  same  name.  To  add  a  folder  specification  to  the
  208.        existing   list,  you  can  execute  any  of  the  following
  209.        commands:
  210.           set path=%path%;newFolderSpec
  211.           path %path%;newFolderSpec
  212.           incr path by ;newFolderSpec
  213.  
  214.    WHERE
  215.        always contains the specification of the current folder.
  216.  
  217.        MacDOS  updates  WHERE  every  time  you  change  volume  or
  218.        directory.
  219.  
  220.        This  variable  lets  you "go back" to  the  initial  folder
  221.        after  using  CHDIR to attach to other folders and  volumes.
  222.        To  do  this, you must save WHERE by copying it  to  another
  223.        variable before attaching to the new folder. For example:
  224.           set back=%where%
  225.           chdir anotherFolder
  226.           ...
  227.           chdir %back%
  228.  
  229.    CREATOR
  230.        stores  the file creator that MacDOS uses when creating  new
  231.        files. By default, the creator is 'ttxt' (ie. TeachText).
  232.  
  233.        You  can  set it to the creator of your preferred editor  or
  234.        word  processor. You can also set it to 'mDOS' if  you  want
  235.        to  create  batch  programs. The  alternative  would  be  to
  236.        create the files and then use REN to change their creators.
  237.  
  238.        Note  that  MacDOS  only uses the first four  characters  of
  239.        this  variable. Therefore, you can use the rest of the  line
  240.        for comments.
  241.  
  242.    QUOTE
  243.        stores  the  character used by MacDOS to  delimit  file  and
  244.        folder   names  which  contain  spaces  and  other   special
  245.        characters. The default is the double quote character.
  246.  
  247.        By  changing QUOTE, you can access file names which  contain
  248.        double quote characters:
  249.           set quote=#
  250.           rename #with "quotes"# #without quotes#
  251.           del bla"bla
  252.           set quote=
  253.  
  254.    FONTSIZE
  255.        stores  the point size of the characters used in the console
  256.        window.
  257.  
  258.        The  default  is 9, but the values 12, 18, 24,  and  36  are
  259.        also  legal.  Other values are rounded down to  one  of  the
  260.        permitted  sizes,  except values  lower  than  9  which  are
  261.        rounded up.
  262.  
  263.    DOSERR
  264.        stores  the  code  of  the last error. As  error  codes  are
  265.        always  positive numbers (see appendix A), zero can be  used
  266.        as a no-error condition.
  267.  
  268.        MacDOS  updates  this  variable whenever  an  error  (not  a
  269.        warning)  occurs,  but  does not reset  it  when  a  command
  270.        completes    successfully.    Therefore,    it    is    your
  271.        responsibility to remove it or initialise it to zero.
  272.  
  273.        You  can  obtain  the  error  message  corresponding  to   a
  274.        particular error code with the command SHOW.
  275.  
  276.    SHOWAE
  277.        tells  MacDOS  whether  it  should  display  incoming  Apple
  278.        Events.
  279.  
  280.        MacDOS  only  checks whether this variable  exists  or  not,
  281.        completely  ignoring its value. For a list of  Apple  Events
  282.        supported  by  MacDOS, please refer to the  section  "MacDOS
  283.        Scripting".
  284.  
  285.    TIMEOUT
  286.        Stores  the  number of seconds that MacDOS waits  for  piped
  287.        messages to go through a chain of MacDOS extensions.  Please
  288.        refer to the section "MacDOS Extensions" for the details.
  289.  
  290.